This sample demonstrates the subtleties needed to create a PPC Toolbox keychain item. PPC Toolbox uses generic password keychain items, however it stores the address of the remote machine in an non-obvious fashion. This sample shows how to ‘bless’ a generic password keychain item so that it can be used by the PPC Toolbox.
The ultimate goal of this sample is to allow you to programmatically send Apple events to a remote machine without any user interaction. To do this you will also need the code sample from DTS Technote 1176 “Mac OS 9”.
For historical reasons the sample code is packaged in the form of an AppleScript scripting addition ('osax'). Thus it is also a good example of a native scripting addition, as described in DTS Technote 1164 “Native Scripting Additions”.
This sample requires Mac OS 9 (or later) because Mac OS 9 is the first system that included a keychain and a PPC Toolbox that consults it.
Packing List
The sample contains the following items:
• PPCToolboxKeychain.mcp — The project file used to build the scripting addition. This project can also build a testbed application used for debugging.
• PPCToolboxKeychain.c — The sample code itself.
• PPCToolboxKeychain.h — Constants shared between the C and Rez source.
• PPCToolboxKeychain.r — A Rez definition of the scripting additions Apple event terminology.
• Testbed.prefix — A prefix file used by the Testbed target to create the testbed application.
• MIB Bits — Parts of the DTS sample code library MoreIsBetter that are required to build the sample.
• PPC Toolbox Keychain — A compiled version of the scripting addition.
• Create and Bless Keys — A script that demonstrates the use of the sample. See the next section for details.
Using the Sample
IMPORTANT: Not not try to use this sample without MacsBug installed. To prevent end users from using this sample in a production environment the code drops into MacsBug when it is loaded and unloaded. If you don’t have MacsBug installed your system will crash.
1. Start by making sure that you’re running Mac OS 9 or later, and that you have created a default keychain.
2. Drop the compiled scripting addition on to your System Folder. It will get auto-routed to your Scripting Additions folder.
3. Launch Script Editor. It will probably drop into MacsBug with the message “FragmentInit”. Continue by hitting command-G.
4. Open the “Create and Bless Keys” script.
5. Modify the script for your own environment. Specifically, change the “name”, “account”, “password”, “service”, and “address” data to values appropriate for your remote machine.
6. Run the script. This will create a PPC Toolbox keychain item. You can confirm this by running Keychain Access.
7. Write an Apple script that communicates with the remote machine you configured in step 5. My favourite is:
tell application "Finder" of machine "Guy Smiley"
every process
end tell
You can run this script and get information from the remote machine without any user interaction.
Building the Sample
The sample was built using the CodeWarrior Pro 2 C compiler with Universal Interfaces 3.3.2. You should be able to just open the project, select the “osax” target, and choose Make from the Project menu. This will build the “PPC Toolbox Keychain” scripting addition.
How it Works
The sample script relies on Keychain Scripting to do the bulk of the work creating an generic keychain item. Once Keychain Scripting has created the item the script sends the bless program linking key Apple event to modify the keychain item for PPC Toolbox. This results in the BlessKeyHandlerProc routine (PPCToolboxKeychain.c) being called. That routine extracts the Apple event parameters, finds the correct generic keychain item, and then calls KCSetAttribute to set the kGenericKCItemAttr based on the incoming address parameter. The format of this attribute varies depending on whether the keychain item is for an AppleTalk or TCP/IP machine.
1. For AppleTalk, the item is a packed NBPEntity.
2. For TCP/IP, the item is LocationNameRec with locationKindSelector of ppcXTIAddrLocation.
See Technote 1176 for more details on these structures.
Caveats
The code for parsing URLs is somewhat lame. While I’m fairly confident that it won’t crash, it could be both smarter and more forgiving. Fortunately this doesn’t affect the value of this sample as people who want to send remote Apple events usually have the remote address in non-URL form (–:
Credits and Version History
If you find any problems with this sample, mail <DTS@apple.com> and I’ll try to fix them up.
1.0d1 (May 2000) shipped to a limited number of developers for testing purposes only.
1.0b1 (Sep 2000) Added gAdditionReferenceCount to allow for unloading. Wrote this documentation. This release is the first general release.
